Amiga News 95

home *** CD-ROM | disk | FTP | other *** search

/ Amiga News 95 / Amiga News 95.iso / dpat / dpat18 / aush_v1.52 / aushenglish.doc < prev next >

Wrap

Text File | 1992-02-22 | 32KB | 771 lines

AUSH - Reference Manual 1. Foreword This manual describes release 1.52 of the utility AUSH. This program is (c)1992 by Denis GOUNELLE, any commercial usage or selling without author's written authorization is strictly forbidden. You can copy and spread this program at the following conditions: - all the files must be provided - none of the file must have been modified - you don't charge more than $6 for copy fee In spite of several tests, no warranty is made that there's no errors in AUSH. YOU USE THIS PROGRAM AT YOUR OWN RISKS. In no event will I be liable for any damage, direct or indirect, resulting of the use of AUSH. 2. Introduction AUSH (Amiga Ultimate SHell) is a new command line interpreter, designed to replace Commodore's shell. It takes several features from some UNIX and Amiga shells I used (sh, csh, tcsh 6.00.03, AShell 1.3 and Csh 4.01A) but also adds a lot of new possibilities, while remaining almost fully compatible with Commodore or ARP shells. Critics and suggestions will be welcomed. Write to the following address: M. GOUNELLE Denis Boite 71 6, rue des cailloux 92110 CLICHY - FRANCE The command line editor has been written starting from Csh's one (v4.02 by Matt DILLON/Steve DREW/Carlo BORREO/Cesare DIENI). Many thanks to Pierre ARDICHVILI, Jean-Yves PROUX, Jean-Philippe RAPP, and Michel SCHINZ for tests and suggestions. Thanks to Josef EGLOFF for translating error messages in german. 3. Installation Under system release 1.3, you must first install the ARP library (if not allready done) in your "LIBS:" directory. Then copy the "AUSH" (the shell itself) and "NewAUSH" (command to start a new shell) files in your "C:" directory. Both AUSH and NewAUSH are written in "pure" code, and so can be made resident. 4. The NewAUSH command The NewAUSH command is the command to start a new shell (as Commodore's NewCLI and NewShell). It won't work unless you put AUSH in the command search directories defined by the "Path" command. To start a new shell, enter the following command: NewAUSH [window specification] Example: NewAUSH CON:0/11/640/180/AUSH From WorkBench, you must create a "Project" icon, and specify NewAUSH complete path in the "DEFAULT TOOL" field. You can also specify a stack size ("STACK" field) and a window specification ("TOOLS TYPE" field, the syntax is "WINDOW=specification"). 5. Command line parsing Each command you enter is parsed by AUSH before it tries to execute it. First, alias substitution is performed on command name. An alias can be defined by another one (CAUTION: there's no test for alias recursion !). You can prevent alias substitution by adding a "\" character before command name (e.g. "\ls df0:"). All command arguments are also scanned, and the following substitutions are performed: ; start comment (the rest of the line is discarded). ^chr replaced by "CTRL-chr" if "chr" is a letter, by "chr" otherwise. =n replaced by the n-th directory in the directory stack. $var replaced by the value of the given variable (the local variables are scanned first, then the global variables, and last the ARP/Commodore and Manx variables list) or by an empty string is this variable is not defined. Variable names may be put between brackets : to display the value of variable "foo" followed by "hello", you must type "echo ${foo}hello" instead of "echo $foohello". Variable names may be followed by a function name. This function will be applied on variable value (if variable is defined) during substitution. Effective variable value is not modified. Function supported are: lower convert to lower-case upper convert to upper-case first extract first character slead skip leading tabs or spaces len return len The syntax is "$var:function", e.g. "$config:lower" or "${config:lower}". pattern replaced by the name of all files matching the pattern. A pattern is a word with at least one of the ARP (under system 1.3) or AmigaDOS (under system 2.0) meta-characters. Take care that some commands (list, copy, ...) expect the pattern and expand it themselves, so you'll have to quote it (e.g. "list '#?.o'") in order to avoid conflicts. {expr} replaced by the result of the expression (see below for syntax). !! replaced by last command in history. !n replaced by n-th command in history. !str replaced by last command beginning with "str" in history. `cmd` replaced by the first output line of specified command. Leading spaces are deleted, the line is considered as a whole word and is not parsed again. Example: "set foo `type config`" copies the first line of "config" file in a local variable named "foo". \chr escape the meaning of the "chr" character. 'str' copies "str" without parsing (except for the "\chr" form). "str" copies "str" without parsing (except for "^chr", "=n", "$var", "{expr}" and "\chr" forms, pattern expansion is not disabled). >file specify output redirection. If the file does not exist it is created, otherwise it is truncated to zero length. >>file specify output redirection. If the file does not exist it is created, otherwise output is append to previous file's content. <file specify input redirection. @pri run command at priority "pri" (can be specified anywhere on the command line). &[pri] run command in background [at priority "pri"] (can be specified anywhere on the command line). Under 1.3 system release, command line length is limited to 256 characters for external commands. AUSH also recognize the following constructions: cmd1|cmd2|... execute commands with "pipes" (the output of the commands at the left of the "|" character is used as input by the commands to the right) as long as return code is zero. cmd1,cmd2,... execute commands as long as return code is zero. You can also specify pipes, e.g. "cd ram: , list | wc , delete foo" is a valid command. Return code of such commands is the return code of the last command executed. Only the last command can be runned in background. 6. Variables With AUSH, you can define local and global variables in order to store any numeric or alphanumeric value. Valid characters for variable names are lowercase and uppercase letters, digits and the underscore character. AUSH distinguish lower case and uppercase letters when searching for a variable. A global variable is "visible" at any execution level. It can't be destroyed. Notice that these variable are not ARP/Commodore variables. They are not shared between several shells running at the same time. A local variable is "visible" only at the execution level where it has been defined. When comming back to the previous execution level, all local variables are destroyed. Some variables are used to control AUSH behaviour (see below for description). 7. Expressions AUSH can compute integer expressions in reverse polish notation. You can use variables in such expressions, if their value is numeric. You can enter hexadecimal values (e.g.: 0x13e). Result is displayed in decimal. Operators are: + addition - subtraction * multiplication / integer division % remainder of integer division < shift left > shift right & and | or sx store stack top in register x (x = 0 to 9) lx push register x (x = 0 to 9) HEX change output base to hexadecimal Registers are set to zero when you start AUSH, and are not modified between two expression evaluations. Numbers and operators must be separated by at least one space. Examples: echo { 34 3 / 4 + } => 15 echo { 7 3 - } => 4 echo { 10 -2 + } => 8 set cpt 3 echo { $cpt 2 * } => 6 set cpt { $cpt 1 + } echo $cpt => 4 8. Command line editing Command line editing is enabled by setting the "lineedit" variable to "1". AUSH takes control of the shell window, and recognize the following keys: left previous character. right next character. shift-left previous word. shift-right next word. shift-up last command in history beginning with the current line. up previous command in history. down next command in history. ^A beginning of line. ^B previous character. ^E end of line. ^F next character. ^K delete end of line. ^L refresh line. ^N next command in history. ^P previous command in history. ^T first command in history. ^W delete end of word. ^X kill current line. ^Z last command in history. RETURN save command and execute it. ESC save command but don't execute it. ^V suppose that previous word is a variable name, and replace it by it's value. Example: echo version<^V> => echo 1.10 TAB filename/varname completion. Example: cd ram: list Cl<TAB> => list ClipBoards/ echo $hi<TAB> => echo $history If the prefix you gave matches several names, it is extended up to the point of ambiguity and all the possibility are displayed. To perform filename completion, AUSH adds the content of the "filepat" variable to the prefix and expands the resulting pattern. ^D displays the list the possibilities for filename/ varname completion, but does not modify command line. HELP opens a file requester. If you select a file, it's name will be added to the command line. f1 to f10 replaced by the content of "f1" to "f10" variables (of "F1" to "F10" if shifted). The "keys" special variable may be used to remap control keys (see below). IMPORTANT: the line editor sometimes suddenly stops to react to whatever you type. You will generaly get out of this situation just by typing a "|" (SHIFT-\). 9. Other features AUSH can execute script files (which are text files containing several commands) just as any other program. In such files, the local variable "argc" is set to the number of arguments you gave. AUSH also set some "pseudo" local variables (the "set" command won't show them, and you can't modify them) : the variable "0" is set to the script file name, "*" to the argument list (each argument separated by a space) and "1", "2",... variable to the arguments themselves. On startup, AUSH tries to execute the "S:.aushrc" script file. AUSH can save your commands in an history. The "history" variable tells how much commands are to be kept. The "history" command displays history content. The "savehist" variable tells how much commands must be saved when you quit AUSH. This file is read when AUSH starts, and all commands in the file are stored in the command history. You can define the "histfile" variable to the name of the file to use to save/load command history. Default name is "S:.history". The alias "dircmd" (if defined) is executed each time you enter a directory name as a command name (without arguments, redirection, pipe, or background specification). So, "alias dircmd cd" gives you an "implicit cd": to change of directory you just have to enter the new directory name. Of course, you can define a more complex alias, like "alias dircmd 'cd [] , list QUICK FILES'". AUSH manage a stack of directory (64 entries). You push a directory with "pushd", you pop a directory with "popd", and you list the stack content with "dirs" (all these internal commands are described below). You can use this stack in you commands, with the "=n" form (replaced by the n-th directory in the stack). With the default stack of 4000 bytes, AUSH can't execute more than about 15 nested script files and/or loops (you'll get the error "not enough stack space !"). If the name of the output redirection file is "TTY" (i.e. ">TTY" or ">>TTY") the output will be redirected to the shell's window. This may be useful to in a script file, to display a message when all output have been redirected to a file. Pipes are handled via temporary files in the "T:" directory, unless I've try to use "PIPE:" and "FIFO:" handlers. The "T:" directory is also used for command substitution and loop execution. A command like "cmd &" is the same as "run cmd" under Commodore or ARP shells. AUSH will wait for *ALL* background commands to finish before terminate. Use the "jobs" command to list background commands. 10. Internal commands These commands can't be runned in background, but can be input and/or output redirected. They always return 0 (RETURN_OK) or 20 (RETURN_FAIL). "set" and "setvar" commands display variables with their attributes ("x" for exportable, "r" for readonly). alias Displays all alias and their definitions. alias name Displays definition of alias "name". alias name 'string' Define alias "name" to the given string. In the string, the "[]" symbol tells AUSH where to copy alias arguments. Unless it is a single word, the string *MUST* be single-quoted. cd [dir] Without argument displays the name of the current directory, otherwise sets current directory to "dir". dirs Displays the directory stack. echo [-c] [args...] Just displays all given arguments, followed by a new-line character (except if you specify the "-c" option). eval Enters expression evaluation mode: every line you enter is supposed to be a expression, which result is displayed. To exit this mode, enter the character "x" alone on a newline. exit [code] Returns to previous execution level, with the specified return code (0 if no arguments). In interactive mode, terminates the shell. export vars... Makes the given local variables "exportable", so they can be read, modified or destroyed by any script file started from the current execution level. for var in val1 val2... valn .... done Performs a loop. The local variable "var" is set to each value in the list, and for each value the loop is executed. After the "done" command, the "var" variable tells for which value the loop was last executed. You can also use the form "for var in val1 .. val2", where "val1" and "val2" are numeric values. Both numbers may be negatives. If "val2" is lower than "val1", loop step will be negative. history [str] Displays the command history. If the optional "str" argument is specified, only commands beginning by the "str" string will be displayed. if [NOT] condition .... [else ....] endif Conditionnal execution. The condition may be: -d name true if "name" if a directory (1) -e name true if "name" exists (1) -f name true if "name" is a file (1) -o name name2 true if "name" and "name2" exist and "name" is older than "name2" (1) -s name true if "name" is not an empty file (1) str = str true if strings are equal str == str true if strings are equal (case-insensitive) n1 LT n2 true if n1 is lower than n2 n1 LE n2 true if n1 is lower than or equal to n2 n1 EQ n2 true if n1 is equal to n2 n1 NE n2 true if n1 is not equal to n2 n1 GT n2 true if n1 is greater than n2 n1 GE n2 true is n1 is greater than or equal to n2 The word "NOT" may be used to invert the condition. Up to 16 "if" commands may be nested. (1) If the letter after the minus sign is an upper-case letter (e.g. "-D"), the test will fail without any AmigaDOS requester if volume is not mounted, if there is no disk in drive, etc... jobs Displays the list of background commands. loadhist Loads immediatly command history from history file. May be useful if you've just changed the "histfile" variable, and want to use the new history file. popd [nb] Without arguments, pops the last directory in the directory stack and make it the current directory. Otherwise, truncs stack size to "nb" entries (i.e. "popd 0" clears the stack). pushd dir Pushes the current directory in the directory stack and sets current directory to "dir". read [-f] var Sets local variable "var" to the first line read on standard input. Returns RETURN_FAIL on end of file. If you specify the "-f" option, the user won't be allowed to enter an empty string. readonly vars... Makes the specified variables "readonly". This works both on local and global variables. set Displays all local variables and their values. set name Displays value of local variable "name." set name value Sets local variable "name" to "value". setvar Displays all global variables and their values. setvar name Displays value of global variable "name." setvar name value Sets global variable "name" to "value". shift Shifts script file arguments: "1" pseudo-variable is set to "2", "2" is set to "3",... The "argc" and "*" variables are updated. source file Execute a script file. If you specify an output redirection, all commands in the file will be redirected. stop [code] Exits a "for...done" loop with the specified return code (0 if no arguments). time <command> Runs the given command and displays the execution time of this command. Can be used for all commands, including internal and background ones. unalias name... Destroys the specified aliases. unset name... Destroys the specified local variables. writehist Writes immediatly command history to history file. Can be useful, for example, before running a program that may crash you Amiga. 11. Special variables These variables are used to control AUSH. You should define them as global variables (that what AUSH does when setting them to their initial value). cmdnum command number (_ShellNumber_CmdNumber, guaranted to be different for each command being executed). cwd current directory. debug if set to "1", displays commands before and after parsing (may be useful to debug script files). delim list of word delimiters for "next word", "previous word" and "delete end of word" functions of the command line editor. Initial value: " :/". filepat string added to current word to perform filename completion. Initial value: "#?". fullhist if set to "1", save all commands in the history. Otherwise, don't save twice again the same command. histfile name of the file to use to save/load command history. If not set, "S:.history" is assumed. histmin minimal length that must have a command in order to be saved in history. Initial value: 3. insert if set to "1", command line edition is in insert mode (overstrike mode otherwise). Initial value: 1. ioerror last IoErr() code sets by an internal command. Initial value: 0. keys allows you to remap control keys. Must be set to a string of lowercase characters, each character setting the control key to use to call one of the command line editor's functions. The corresponding function is found thanks to the position of the letter in the string : position 1 go to beginning of line position 2 previous character position 3 list completion position 4 go to end of line position 5 next character position 6 kill end of line position 7 refresh line position 8 next line position 9 previous line position 10 swap characters position 11 go to beginning of history position 12 replace variable position 13 kill end of word position 14 kill line position 15 go to end of history For example, if the fourth letter is "o", you will have to press ^o to go to end of line. When remapping control keys, avoid to use ^h, ^i, ^j and ^m keys, because they are handled in a special way. Initial value : "abdefklnpstvwxz". language language for error messages. If not defined, or set to something different from "english" (for english) and "deutsch" (for german), messages are in french. lineedit if set to "1", enables AUSH command line editor. noexpand if set to "1", patterns in command lines are not expanded. path command search path. Directory names must be separated by a semi-colon character ";", and the name "." stands for the current directory. If a file with the "s" bit set if found when searching for a command, a "source" command is automatically run on this file. Example: setvar path 'ram:;.;c:;sys:utilities' prompt defines normal prompt. You can include the following sequences: %h current history number %# shell number %i "if...endif" nesting level %l "for...done" nesting level %c current directory ("cwd" variable) %s last return code ("status" variable) %Vname valeur of "name" variable %T time (HH:MM:SS) %d day in the month (1-31) %D day in the week (Mon-Sun) %m month (1-12) %M name of the month (Jan-Dec) %y year (1900-1999) %C CSI character (0x9B) %N carriage return %f size of FAST memory free %v size of CHIP memory free %a size of memory free (FAST+CHIP) Initial value: "%C0;33;40m< %# - #c >%C0;31;40m" prompt2 defines prompt between "if" and "endif". Initial value: "%i> ". prompt3 defines prompt between "for" and "done". Initial value: "%l) ". savehist number of commands to save. If not defined or set to a value lower than 1, nothing is saved. status last return code. titlebar defines the titlebar of the current window (same syntax as for the prompts). trap command(s) to run when CTRL-C or CTRL-D are hit during a script file or a loop execution. I suggest to define it as a local variable, so that each script file could modify it for it's own use. I suggest also to give an "exit" command as last command (e.g. "set trap 'delete $tmpfile , exit 20'"), otherwise execution will not be stopped (so to ignore breaks use "set trap ';'"). If this variable is not defined, execution is stopped with a return code of 20. version current version of AUSH. 12. History v1.00 28-Feb-92, 29564 bytes o First release. v1.10 28-Mar-92, 31828 bytes o When expanding vars, look also in ARP/Commodore and Manx lists. o "^D" key displays possibilities for file/varname completion ; "^B", "^F", "^N" and "^P" keys do the same as "left", "right", "down" and "up" keys. o The command line editor erase cursor while executing a command (faster display). o The file request read the current work to set request initial's directory. o Reset SIGBREAKF signals when returning from command line editing (they are set if you press "^D", "^E" or "^F" keys) o "!!", "!n" and "!string" can be specified anywhere on the command line. o Added -D, -E and -F switches to "if" command. o Added "for var in val1 .. val2" specification to "for...done" command. o Added alias "dircmd". o Add a space after an alias definition without argument (if you enter "alias ls dir", and then type "ls ram:", you will no longer have a "Please insert volume dirram: in any drive" requester). o Error messages in german if the "language" variable is set to "deutsch". o Renamed "setenv" command to "setvar" (no more conflicts with Commodore's command), added "echo" command. o Added special variables "version" and "path", the "ioerror" command is initialized to "0", the "insert" command is initialized to "1", removed "autocd" variable. v1.11 29-Mar-92, 31832 bytes o Bug fixed: The "echo" command can new be output redirected. v1.12 11-Apr-92, 32244 bytes o Load history *after* "S:.aushrc" execution, in order to allow a change of the value of "history" variable in the startup-sequence. o Added "NE", "LE", and "GE" switches to "if" command. o In "for i in val1 .. val2" specification, "val2" may be lower than "val1", and both value may be negative. o No more checking of arguments size for internal commands. o Added "^V" key to command line editor. v1.13 18-Apr-92, 32280 bytes o When searching a command with the "path" variable, check that the object is a file (and not a directory). v1.14 26-Apr-92, 32300 bytes o Two bugs fixed in command substitution: didn't remove the final "`", error in arguments length computation. o Bug fixed in the parser: didn't escaped "<>,;" special meaning when in first position of a quoted string. o Better german messages. v1.15 01-May-92, 32364 bytes o Added "histfile" variable. o Two bug fixed in arguments length computation: forgetted quotes, and didn't add some more space for "splitted" arguments. v1.16 11-May-92, 32404 bytes o Bug fixed: the "-c" option of "echo" command *really* delete the final "\n" (doesn't replace it with a space) v1.20 16-May-92, 32568 bytes o Added "loadhist" and "writehist" commands. o Added "%Vname" specification to prompt syntax. o Parser modified: parse right part of a complex command *after* left part execution, so : - "cd ram: , delete *" does what expected ("*" was expanded before going to "ram:") - all commands in a complex command may be aliases (not only the first one) - you can write a loop in one command ("for i in 1 .. 50 , echo $i , done" didn't worked, now even "cd ram: , for i in *.c , echo $i , compress $i , done , echo fini" does !) v1.21 17-May-92, 32912 bytes o Added "time" command. v1.22 23-May-92, 32944 bytes o Bug fixed in loop handling: when writing commands to temporary file, didn't ensure there was a "\n" character after each command. v1.23 01-Jun-92, 33328 bytes o Several bugs fixed in loop handling (when written on a single line) : now "for i in 1 .. 5,echo $i,done" and "for i in 1 .. 5 , list | wc , done" work. o If a file with the "s" bit set if found, when searching for a command in the path defined by the "path" variable, a "source" command is automatically run on this file. o The "^S" key swaps the two previous characters. o The "^D" and "<TAB>" keys can now be used without prefix, i.e. at the beginning of a line or after a space character. o Bug fixed in command line editor: after a "shift-up" key, the "up" and "down" keys didn't give the expected commands. v1.30 14-Jun-92, 33932 bytes o Fixed several errors detected with "Enforcer" and "Mungwall". o Bug fixed in "shift" command: didn't set "argc" to the good value. o Handles "$*" (list of arguments separated with a space). o Added -f option to "read" command. o "argc" variable is now read-only. o Checks varnames given to internal commands ("pseudo" local variables are not allowed). o "&[pri]" and "@pri" can be specified anywhere on the command line. v1.40 26-Jun-92, 37764 bytes o Now compiled with SAS/C 5.10b (with pragmas and optimization) o Can be made resident ("pure" code) o Bug fixed in strxcat() function: didn't save a2 register o Several changes for better support of 2.04 system release, so: - no more need for "arp.library" - can execute ROM resident/internal commands - AmigaDOS "Execute" command works o Expression evaluator modified: - hex (0x13F) values supported - added "HEX", "<", ">", "&", and "|", operators o Added "-o" switch to "if" command o Bug fixed in "if" command: didn't always UnLock() file v1.41 30-Jun-92, 37864 bytes o Bug fixed in command search: doesn't search path for resident commands v1.42 06-Jul-92, 37872 bytes (Fish #706) o Bug fixed in loop handling "for...done": command redirection was "forgotten" o No more "Enforcer" hits whith "!string" (or "shift-up" in command line editor) when there's no command starting with "string" in history v1.50 21-Aug-92, 37736 bytes o Added global var "keys" (allows to remap control keys) o Optional argument "FROM file" o More checking at startup time: proc->pr_CLI must be a valid pointeur, stop if started from WB, etc... o Bug fixed in expression parsing: displayed result in decimal even if "HEX" was specified o Bug fixed under 1.3 system release: didn't give full command path to function that start command execution v1.51 01-Sep-92, 37808 bytes o Bug fixed in path search: after automatic sourcing of a script (bit "s" detected) the following commands were sometimes also considered like a script (and sourced !!!) o "history str" displays only commands starting with "str" o The "history" command checks CTRL-C while displaying history o Displays command founded when using "!!", "!n" or "!str" forms o Bug fix: when you did a "cd volume:" the $cwd variable didn't ended with a ':' (so problems for example with a "copy df0:foo $cwd") o Bug fixed in file name completion: distinguished lower case and upper case characters. v1.52 22-Sep-92, 40000 bytes o Allow the ${varname} form o Added variable functions (e.g. "$var:function" or "${var:function}") o Added "==" condition to "if" command o Command line length is no longer limitated to 256 characters under system 2.0 o Bug fixed: test "s" protection bit even if full command path name is given o Some bugs fixed in "for...done" loop handling o The $cwd variable now always ended with a ":" or a "/" o If no file correspond to a pattern, displays an error message and don't execute command